/*
 * Copyright (C)  2010 Mario Ivankovits
 *
 * This file is part of jira-webservice-extensions.
 *
 * Ebean is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
 * (at your option) any later version.
 *
 * Ebean is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with jira-webservice-extensions; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 */

package org.sharedSpace.jira.webservice;

import com.atlassian.jira.issue.search.SearchException;
import com.atlassian.jira.rpc.exception.RemoteAuthenticationException;
import com.atlassian.jira.rpc.exception.RemoteException;
import com.atlassian.jira.rpc.soap.JiraSoapService;
import com.atlassian.jira.rpc.soap.beans.RemoteIssue;

public interface SoapExtension extends JiraSoapService {
	/**
	 * Used to check if the webservice is active. Calling this method returns a
	 * constant string.
	 */
	public String ping();

	/**
	 * Get linked issues with specific link type.
	 *
	 * @param token
	 *            user token from login
	 * @param issueIdFrom
	 *            issue on which the inward and outward links should be gotten
	 * @param linkType
	 *            name of the link type to fetch, "" for all types
	 * @throws RemoteException
	 */
	public RemoteIssue[] getLinkedIssues(String token, Long issueIdFrom,
			String linkType) throws RemoteException;

	/**
	 * Retrieve link and link-type info of type <code>linkType</code> (or all if
	 * null) that issueId <code>issueIdFrom</code> links to.
	 *
	 * @param token
	 *            user token from login
	 * @param issueIdFrom
	 *            issue on which the link info should be gotten
	 * @param linkType
	 *            name of the link type to fetch, "" for all types
	 * @param separator
	 *            a separator string to be used between the info items, defaults
	 *            to "|" if null or empty
	 * @return An array of strings with the following format, separated by
	 *         parameter <code>separator</code> or "|" if null or empty:</br>
	 *         (Any information already known is left out, like the
	 *         source-issueKey. Field-comments in round brackets.)
	 *
	 *         <pre>
	 * link.issueKey |
	 * link.issueId |
	 * link.id |
	 * link.isSystemLink ("Y" or "N") |
	 * linkTypeMnemonic ("I" or "O") |
	 * linkType.Id |
	 * linkType.Name |
	 * linkType.Inward (description) |
	 * linkType.Outward (description) |
	 * linkType.Style |
	 * linkType.isSubTaskLinkType ("Y" or "N") |
	 * </pre>
	 *
	 *         The string is always ended with a separator so it can be
	 *         externally 'recognized' if required.</br> Example result
	 *         (2-string array) (requested issueIdFrom = ATH-1.getId()):
	 *
	 *         <pre>
	 * ATH-3|10010|10020|N|I|10011|Related|relates also to|related to||N|
	 * ATH-2|10001|10060|Y|O|10000|jira_subtask_link|jira_subtask_inward|jira_subtask_outward|jira_subtask|Y|
	 * </pre>
	 *
	 *         The first one is a standard 'Related' inward link from
	 *         ATH-3.</br> The second one is a SubTask link from ATH-1 to ATH-2,
	 *         where ATH-2 is the SubTask. The SubTask is both a SystemLink and
	 *         a SubTaskLinkType.
	 * @throws RemoteException
	 */
	public String[] getLinkedInfo(String token, Long issueIdFrom,
			String linkType, String separator) throws RemoteException;

	/**
	 * Get Inward linked issues with specific link type.
	 *
	 * @param token
	 *            user token from login
	 * @param issueIdFrom
	 *            issue on which the outward links should be gotten
	 * @param linkType
	 *            name of the link type to fetch, "" for all types
	 * @throws RemoteException
	 */
	public RemoteIssue[] getLinkedInward(String token, Long issueIdFrom,
			String linkType) throws RemoteException;

	/**
	 * Get Outward linked issues with specific link type.
	 *
	 * @param token
	 *            user token from login
	 * @param issueIdFrom
	 *            issue on which the outward link should be created
	 * @param linkType
	 *            name of the link type to remove
	 * @throws RemoteException
	 */
	public RemoteIssue[] getLinkedOutward(String token, Long issueIdFrom,
			String linkType) throws RemoteException;

	/**
	 * link issue.
	 *
	 * @param token
	 *            user token from login
	 * @param issueIdFrom
	 *            issue on which the outward link should be created
	 * @param issueIdTo
	 *            issue which should receive the inward link
	 * @param linkType
	 *            name of the link type to create
	 * @param unique
	 *            failure if an outward link of type <code>linkType</code>
	 *            already exists
	 * @param replace
	 *            replace all links of type <code>linkType</code> from the
	 *            "from issue".
	 * @throws RemoteException
	 */
	public void linkIssue(String token, Long issueIdFrom, Long issueIdTo,
			String linkType, boolean unique, boolean replace)
			throws RemoteException;

	/**
	 * unlink issue.
	 *
	 * @param token
	 *            user token from login
	 * @param issueIdFrom
	 *            issue on which the outward link should be created
	 * @param issueIdTo
	 *            issue which should receive the inward link
	 * @param linkType
	 *            name of the link type to remove
	 * @throws RemoteException
	 */
	public void unlinkIssue(String token, Long issueIdFrom, Long issueIdTo,
			String linkType) throws RemoteException;

	/**
	 * get issue for specific worklog id.
	 */
	public RemoteIssue getIssueForWorklog(String token, Long worklogId)
			throws RemoteException, SearchException;

	/**
	 * get custom field values for issue.
	 */
	public String[] getCustomFieldValues(String token, Long customFieldId,
			Long issueId) throws RemoteException, SearchException;

	/**
	 * add a component to the project
	 */
	public long addComponent(String token, String projectKey, String name,
			String description, String lead, long assigneeType)
			throws RemoteException, RemoteAuthenticationException;

	/**
	 * remove a component
	 */
	public void removeComponent(String token, String projectKey,
			long componentId) throws RemoteException,
			RemoteAuthenticationException;

	/**
	 * update the name of a component
	 */
	public void updateComponent(String token, String projectKey,
			long componentId, String name, String description, String lead,
			long assigneeType) throws RemoteException,
			RemoteAuthenticationException;

	/**
	 * link an issue to another issue as subtask
	 */
	public void createSubtaskLink(String token, long parentIssueId,
			long subtaskIssueId, long issueTypeId) throws RemoteException;

	/**
	 * Update the full name and email of a user
	 */
	public void updateUser(String token, String userid, String fullName,
			String email) throws RemoteException;
}
